This document is written for Industry software vendors who will need to update their software to interact with the Integrated Multifamily Access eXchange (iMAX) system.
The iMAX system development effort involves designing and building a replacement for the current TRACSMail system. Replacing the current TRACSMail system is deemed necessary because the performance of the current TRACSMail system is unreliable and does not take advantage of newer, faster, and more secure technologies that have been developed for data interchange. As of the end of calendar year 2008, Sprint will no longer provide support for the existing TRACSMail infrastructure. It is vital that this system be replaced and upgraded to current technologies before the current vendor support ends.
The TRACSMail Re-engineering effort encompasses enhancing the functionality of the current TRACSMail system as well as making use of more up-to-date technologies. The purpose of the TRACSMail Replacement Project is part of the larger goal, which is to improve the Department of Housing and Urban Development’s (HUD) program accountability and product and service delivery to its customers and business partners through the improved financial efficacy and efficiency of system processes within the Tenant Rental Assistance Certification System (TRACS).
The iMAX system will continue the existing functionality of the TRACSMail system, allowing the users to send files to TRACS or other iMAX users and to receive files from TRACS and other iMAX users. The objectives and functionality of the iMAX system would include:
· Provide a system for users to submit Section 8 annual certifications and other subsidy vouchers for payments to TRACS and receive TRACS responses.
· Improve user experience by real time acknowledgement after successful Monthly Activity Transmission (MAT) file submission.
· Continue to support communications between property owners, owner agents (O/A) and contract administrators (CA).
· Facilitate system automation by supporting web services to allow third-party software systems to integrate with iMAX system seamlessly.
· Utilize advanced J2EE and web technologies to minimize system downtime.
Users of iMAX will have two means of access to the system: interactively through a web browser, or systematically through web service calls.
Users accessing iMAX through the web browser will need to login and authenticate through HUD’s Web Access Secure Systems (WASS) Single Sign on. Once logged in and authenticated, users would need to provide their iMAX user id and password, which is the TRACSMail id and password currently being used in the TRACSMail system. Users would then be able to upload a file(s) to TRACS or other iMAX users, view and/or download responses from TRACS or other iMAX users, or view files sent to TRACS or other iMAX users. Additionally, users can manage their iMAX user id profile through the web browser.
Users accessing iMAX through the web services will require their software system to make calls to iMAX through the web services. The calls will require the software system to provide a WASS user id and password as well as an iMAX user id and password. Then there will be specific calls for the software systems to upload file(s) to TRACS or other iMAX users, receive a list or download files from TRACS or other iMAX users, and to receive a list of files sent to TRACS or other iMAX users.
This document will focus on accessing iMAX through web service calls.
The iMAX system is a layered architecture composed of loosely coupled modules. The architecture lends itself to reducing the impact on clients when a module needs to be changed in order to quickly accommodate changing infrastructural or technological advances. The architectural layer that most deeply impacts any Industry software vendor or any business partner with HUD is the web service module. The web service module is the gateway into HUD’s infrastructure. It is built with security to adhere to HUD’s security policies and with industry standards to maximize interoperability. The level of interoperability is dictated in part by dominant software platforms generally available to anyone wishing to be a business partner with HUD or provide integration services to those who do business with HUD. Interoperability is also dictated by the usefulness of the web service operations. The process of defining operations to maximize interoperability can put an enormous burden on the client and HUD in order to communicate effectively. The following subsections cover the different technologies used. This information is provided as a high level overview and is not meant as a detailed reference. When appropriate, specific implementation details are addressed as it concerns iMAX.
Security is always a critical necessity when data exchange is concerned, especially when the data exchange occurs through open channels. Three areas of security concern were addressed when designing iMAX. These areas are: data security, authenticity of the caller, and authorization privileges.
Data security is addressed at the transport level. All communications with iMAX is done through HTTP over SSL. All data transmissions are encrypted. Please consult your network administrator if you communicate with the internet through a proxy server.
HUD policy requires entities communicating electronically with HUD that are outside of HUD’s network be authenticated. Business partners wishing to communicate with HUD electronically are required to be registered and receive HUD business partner credentials, which is a WASS id and password. You can register with HUD’s security services at HUD Secure Systems to receive the user id and password. These credentials are required for each individual that does business with HUD. Whether communicating through a browser to access HUD resources or communicating directly with iMAX, clients will need to provide their credentials.
iMAX uses BASICAUTH authentication mechanism for all web service calls. The client will need to configure their client component to pass along WASS user id and password with each web service call. The authentication time is miniscule compared to the processing time needed for any web service call. The mechanism for setting up BASICAUTH authentication on the client side is dependent on the software platform being used and would be outside of the web service Simple Object Access Protocol (SOAP) message. For passing the WASS MID and password, use basic authentication for web services over HTTP/S. The following is a link with examples for .NET: http://www.devx.com/codemag/Article/16762/0/page/2. Please consult any available software platform documentation concerning setting up authentication for web service calls.
Once a client is authenticated, depending on the system, the client can be asked to provide system specific user credentials. All communications to iMAX require that the client provide an iMAX user id and password, previously known as the TRACSMail user id and password. The iMAX id and password are available to a business entity rather than an individual. You can request a TRACSMail id by contacting the Multifamily Helpdesk at 1-900-767-7588 or email TRACS@hud.gov. Since all communications are encrypted at the transport level, the user id and password are safe. Unlike client authentication where the WASS user id and password are passed along as part of the request header, the client authorization information is passed along as part of the operation parameter in the SOAP message.
Web services can be implemented in any way that provides some service through the internet. Web service does not predefine what transport protocol to use nor the formatting of the messages going back and forth. However, to accommodate the variance of software platforms available, web services defined by the usage of the following technologies are provided to those wishing to communicate electronically with HUD. More detailed discussions about each technology are covered in the following subsections.
Hypertext Transport Protocol (HTTP) is a transport protocol. It sits on top of TCP/IP. Most internet technology platforms understand how to encode and send and receive and decode messages that are sent over HTTP.
Most communications on HTTP is not encrypted and is sent as plain text. It is possible to snoop HTTP communications and see the contents without any decoding of the raw data. Most informational communication through the internet does not require any security. For communications where sensitive data is transmitted, it is necessary to encrypt the data to ensure confidentiality. Secure Socket Layer (SSL) addresses this need. Both the service consumer and provider need to be able to communicate over SSL. Most software platforms support the ability to communicate using a secure connection using SSL. The Service providers will need to configure their services to use SSL as well.
As mentioned in Section 1.3.1.1, Data Security, all communications with iMAX are conducted using HTTP over SSL for the purpose of data security and integrity.
Extensible Markup Language (XML) provides a means to format data or a document so that the data and/or document can be visually readable as well as readable by most software platforms. The XML schema document uses XML to specify a specific language set that a service provider understands. Clients wishing to communicate with a service provider must use the specified XML Schema Definition (XSD) to format their messages so that the service provider understands what to do.
Though the Monthly Activity Transmission (MAT) files submitted to iMAX are not currently formatted using XML, the surrounding technologies that create and read the transmission messages use XML. Therefore, it is necessary that anyone who wishes to communicate with iMAX have a foundational understanding of XML and XSD.
Simple Object Access Protocol (SOAP) uses an XML defined language set to define a message format that can be understood by both clients and web service providers. SOAP defines the message, message header, and message content for all communications. It is good to have an understanding of what role SOAP plays in consuming and providing web services
The details at the SOAP level are usually hidden from the client software development platform as it can be a confusing task trying to manually create, send, and receive SOAP messages. It is highly discouraged to manually manipulate SOAP messages.
Consumers of web services need a Web Service Description Language document (WSDL) from the service provider. Without one, it is impossible to know how to organize the SOAP message and the address to send the SOAP message.
The WSDL document can be distributed through a web browser, HTTP request, or as a file. The WSDL document contains all that is necessary for a web service consumer to create components that consume web services. It provides messages, operations, parameters, data types, transport protocol, messaging protocol, and address of the web service.
Note: The iMAX WSDL will be provided along with this document on the TRACS documents webpage: http://www.hud.gov/offices/hsg/mfh/trx/trxdocs.cfm.
This section addresses some conventions used specifically for iMAX.
iMAX permits multiple and concurrent web service requests using the same WASS user id and iMAX user id. iMAX will not set timeouts for a call; any time outs will need to be set on the vendor software side. The duration and timeout of a request is configured on the client side. For transmission of large amounts of data, the timeout of a request should be set accordingly. iMAX does not retain a conversational state between web service calls. Each call is a discrete and independent call of any subsequent calls. This requires that each call provide both the WASS user id and iMAX user id. The authentication and authorization of each call is miniscule compared to the overall transaction time. More information regarding sample timeouts can be provided after testing/UAT is completed.